---
title: "Tooltip"
description: "Tooltips display a brief, informative message that appears when a user interacts with an element."
---

import {tooltipContent} from "@/content/components/tooltip";

# Tooltip

Tooltips display a brief, informative message that appears when a user interacts with an element.

<ComponentLinks component="tooltip" styles="popover" reactAriaHook="useTooltipTrigger" />

---

<CarbonAd/>

## Installation

<PackageManagers
  showGlobalInstallWarning
  commands={{
    cli: "npx heroui-cli@latest add tooltip",
    npm: "npm install @heroui/tooltip",
    yarn: "yarn add @heroui/tooltip",
    pnpm: "pnpm add @heroui/tooltip",
    bun: "bun add @heroui/tooltip"
  }}
/>

## Import

<ImportTabs
  commands={{
    main: 'import {Tooltip} from "@heroui/react";',
    individual: 'import {Tooltip} from "@heroui/tooltip";',
  }}
/>

> For individual installation, please note that you should add `./node_modules/@heroui/theme/dist/components/popover.js` to your `tailwind.config.js` file instead since tooltip reuses popover styles.

## Usage

<CodeDemo title="Usage" files={tooltipContent.usage} />

### With Arrow

<CodeDemo title="With Arrow" files={tooltipContent.arrow} />

### Colors

<CodeDemo title="Colors" files={tooltipContent.colors} />

### Placements

<CodeDemo title="Placements" files={tooltipContent.placements} />

### Offset

<CodeDemo title="Offset" files={tooltipContent.offset} />

### Controlled

<CodeDemo title="Controlled" files={tooltipContent.controlled} />

### With Delay

You can control the `open` and `close` delay of the tooltip with `delay` and `closeDelay` props.

<CodeDemo title="With Delay" files={tooltipContent.delay} />

Hovering over the second button shows the tooltip immediately. If you wait for a delay before hovering
another element, the delay restarts.

<CodeDemo title="With Delay Multiple" files={tooltipContent.delayMultiple} />

### Custom Content

<CodeDemo title="Custom Content" files={tooltipContent.customContent} />

### Custom Motion

Tooltip offers a `motionProps` property to customize the `enter` / `exit` animation.

<CodeDemo title="Custom Motion" files={tooltipContent.customMotion} />

> Learn more about Framer motion variants [here](https://www.framer.com/motion/animation/#variants).

## Slots

- **base**: The main tooltip slot, it wraps the tooltip content.
- **arrow**: The arrow slot, it wraps the tooltip arrow, the placement of the arrow is based on the tooltip placement, e.g. `data-[placement=top]:...`.

### Custom Styles

You can customize the `Tooltip` component by passing custom Tailwind CSS classes to the component slots.

<CodeDemo title="Custom Styles" files={tooltipContent.customStyles} />

<Spacer y={4} />

## Data Attributes

`Tooltip` has the following attributes on the `base` element:

- **data-open**:
  When the tooltip is open. Based on tooltip state.
- **data-placement**:
  The placement of the tooltip. Based on `placement` prop. The arrow element is positioned based on this attribute.
- **data-disabled**:
  When the tooltip is disabled. Based on `isDisabled` prop.

<Spacer y={4} />

## Accessibility

- Keyboard focus management and cross browser normalization.
- Hover management and cross browser normalization.
- Labeling support for screen readers (aria-describedby).
- Exposed as a tooltip to assistive technology via ARIA.
- Matches native tooltip behavior with delay on hover of first tooltip and no delay on subsequent tooltips.

<Spacer y={4} />

## API

### Tooltip Props

<APITable
  data={[
    {
      attribute: "children*",
      type: "ReactNode[]",
      description: "The children to render. Usually a trigger element.",
      default: "-"
    },
    {
      attribute: "content",
      type: "ReactNode",
      description: "The content to render inside the tooltip.",
      default: "-"
    },
    {
      attribute: "size",
      type: "sm | md | lg",
      description: "The tooltip size. This change the content font size.",
      default: "md"
    },
    {
      attribute: "color",
      type: "default | primary | secondary | success | warning | danger",
      description: "The tooltip color theme.",
      default: "default"
    },
    {
      attribute: "radius",
      type: "none | sm | md | lg | full",
      description: "The tooltip border radius.",
      default: "md"
    },
    {
      attribute: "shadow",
      type: "none | sm | md | lg",
      description: "The tooltip shadow.",
      default: "sm"
    },
    {
      attribute: "placement",
      type: "TooltipPlacement",
      description: "The placement of the tooltip relative to its trigger reference.",
      default: "top"
    },
    {
      attribute: "delay",
      type: "number",
      description: "The delay in milliseconds before the tooltip opens.",
      default: "0"
    },
    {
      attribute: "closeDelay",
      type: "number",
      description: "The delay in milliseconds before the tooltip closes.",
      default: "500"
    },
    {
      attribute: "isOpen",
      type: "boolean",
      description: "Whether the tooltip is open by default (controlled).",
      default: "-"
    },
    {
      attribute: "defaultOpen",
      type: "boolean",
      description: "Whether the tooltip is open by default (uncontrolled).",
      default: "-"
    },
    {
      attribute: "offset",
      type: "number",
      description: "The distance or margin between the reference and popper. It is used internally to create an offset modifier.",
      default: "7"
    },
    {
      attribute: "containerPadding",
      type: "number",
      description: "The placement padding that should be applied between the element and its surrounding container.",
      default: "12"
    },
    {
      attribute: "crossOffset",
      type: "number",
      description: "The additional offset applied along the cross axis between the element and its anchor element.",
      default: "0"
    },
    {
      attribute: "showArrow",
      type: "boolean",
      description: "Whether the tooltip should have an arrow.",
      default: "false"
    },
    {
      attribute: "shouldFlip",
      type: "boolean",
      description: "Whether the tooltip should change its placement and flip when it's about to overflow its boundary area.",
      default: "true"
    },
    {
      attribute: "triggerScaleOnOpen",
      type: "boolean",
      description: "Whether the trigger should scale down when the tooltip is open.",
      default: "true"
    },
    {
      attribute: "isKeyboardDismissDisabled",
      type: "boolean",
      description: "Whether pressing the escape key to close the tooltip should be disabled.",
      default: "false"
    },
    {
      attribute: "isDismissable",
      type: "boolean",
      description: "Whether to close the overlay when the user interacts outside it.",
      default: "false"
    },
    {
      attribute: "shouldCloseOnBlur",
      type: "boolean",
      description: "Whether the tooltip should close when focus is lost or moves outside it.",
      default: "true"
    },
    {
      attribute: "motionProps",
      type: "MotionProps",
      description: "The props to modify the framer motion animation. Use the variants API to create your own animation.",
      default: "-"
    },
    {
      attribute: "portalContainer",
      type: "HTMLElement",
      description: "The container element in which the overlay portal will be placed.",
      default: "document.body"
    },
    {
      attribute: "updatePositionDeps",
      type: "any[]",
      description: "The dependencies to force the tooltip position update.",
      default: "[]"
    },
    {
      attribute: "isDisabled",
      type: "boolean",
      description: "Whether the tooltip is disabled.",
      default: "false"
    },
    {
      attribute: "disableAnimation",
      type: "boolean",
      description: "Whether the tooltip is animated.",
      default: "false"
    },
    {
      attribute: "classNames",
      type: "Partial<Record<\"base\"｜\"content\", string>>",
      description: "Allows to set custom class names for the tooltip slots.",
      default: "-"
    }
  ]}
/>

### Tooltip Events

<APITable
  data={[
    {
      attribute: "onOpenChange",
      type: "(isOpen: boolean) => void",
      description: "Handler that is called when the tooltip's open state changes.",
      default: "-"
    },
    {
      attribute: "shouldCloseOnInteractOutside",
      type: "(e: HTMLElement) => void",
      description: "When user interacts with the argument element outside of the tooltip ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the tooltip. By default, onClose will always be called on interaction outside the overlay ref.",
      default: "-"
    },
    {
      attribute: "onClose",
      type: "() => void",
      description: "Handler that is called when the tooltip should close.",
      default: "-"
    }
  ]}
/>

### Tooltip types

<Spacer y={1} />

#### Tooltip Placement

```ts
type TooltipPlacement =
  | "top"
  | "bottom"
  | "right"
  | "left"
  | "top-start"
  | "top-end"
  | "bottom-start"
  | "bottom-end"
  | "left-start"
  | "left-end"
  | "right-start"
  | "right-end";
```

#### Motion Props

```ts
export type MotionProps = HTMLMotionProps<"div">; // @see https://www.framer.com/motion/
```
